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ABSTRACT 

A computer -program  documentation  procedure  to  replace 
conventional  flow  diagrams  for  tactical  data  systems  is 
summarized.  Two  types  of  graphic  documentation  are  described: 
Program  Flow  Diagrams  and  Functional  Flow  Charts. 
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1.  INTRODUCTION 


Study  of  the  documentation  of  computer  programming  for  tactical  data 
systems  reveals  many  shortcomings  in  the  flow  charts  and  program  listings  provided 
for  maintenance  and  operational  use.  As  a result  of  these  shortcomings,  oper- 
ational and  maintenance  personnel  must  often  spend  long  periods  of  time  studying 
these  charts  in  order  to  clearly  understand  system  functions  — a great  waste  of 


manpower. 


To  assist  in  resolving  the  problem,  this  report  summarizes  an  approach  to 
computer-program  documentation  that  was  first  described  in  ARINC  Research's 
publication  Tactical  Data  System  Computer  Programming  Specification*.  The  method 
replaces  conventional  flow  diagrams  with  the  Program  Plow  Diagrams  and  Functional 
Plow  Charts  discussed  in  the  following  chapter.  An  example  of  computer-program 
documentation  according  to  this  method  is  presented  in  Chapter  3- 


2.  DETAILS  OF  THE  DOCUMENTATION  METHOD 


2.1  Description  of  the  Documents 

The  Program  Plow  Diagrams  and  Functional  Flow  Charts  required  by  ARINC  Research's 
computer-programming  specification  use  geometric  shapes,  symbols,  and  supplementary 
notations  to  Illustrate,  on  a single  sheet,  the  logical  flow  of  data  and  the  sequence 
of  operations  In  a digital  computer  program,  routine,  or  subroutine.  The  two  types 
of  graphic  documentation  are  described  as  follows: 

Program  Flow  Diagram  - The  Program  Flow  Diagram  Is  a basic  document  that 
Illustrates  the  decision  processes  and  the  resultant  actions  In  terms  of 
design  logic.  The  design  logic  Includes  tests  and  actions;  examples  of 
tests  are  "Target  Closer  Than  200  Miles",  "Target  Displaying  IFF",  and 
"Target  Confirmed";  examples  of  actions  are  "Set  Drop  Track  Bit",  "Subtract 
Range  from  Previous  Range",  and  "Compute  New  Target  Position".  When  multiple 
actions  are  to  be  performed  after  a test  or  series  of  tests,  optional  sequences 
must  be  Identified  to  provide  flexibility  In  the  programming  process.  Thus, 
the  programmer  can  attempt  various  combinations  to  Improve  the  efficiency  of 
the  program. 

Functional  Flow  Chart  - The  Functional  Flow  Chart  Illustrates  the  programming 
process  required  to  satisfy  the  logic-design  requirements  of  the  Program  Flow 
Diagram,  and  the  options  selected.  In  addition  to  containing  blocks  for  each 
logical  decision  and  action,  the  Functional  Flow  Chart  contains  blocks  for 
programming  operations  such  as  masking,  shifting.  Incrementing,  clearing, 
storing,  exclusive  CRing,  etc.  The  terminology  In  the  decision  and  action 
boxes  is  an  encoding  of  the  respective  requirement  illustrated  on  the 
Program  Flow  Diagram.  For  example,  where  the  Program  Flow  Diagram  displays 
"Set  Drop-Track  Bit",  the  Functional  Flow  Chart  displays  "Set  DT=1",  where 
DT  has  been  defined  as  the  word  section  or  table  that  contains  drop-track 
information. 

2.2  Preparation  of  the  Documents 

Program  Flow  Diagrams  and  Functional  Flow  Charts  are  prepared  to  illustrate 
the  following  program  divisions: 

• The  overall  program,  containing  major  routines 

• The  major  routines,  containing  major  subroutines 

• The  major  subroutines 


A 


2.2.1  Degree  of  Detail 

The  degree  of  detail  Is  Influenced  by  the  problem,  by  the  programming 
language  to  be  used,  and  by  the  level  of  program  subdivision  being  flow-charted. 
Flow  diagrams  that  deal  with  low-level  program  subdivisions  require  more  detail 
than  flow  charts  that  deal  with  the  higher  levels.  Lines  connecting  the  boxes 
Illustrate  the  flow  within  the  diagrams,  with  separate  lines  used  for  each  basic 
flow.  When  direction  of  flow  Is  not  readily  apparent,  arrowheads  show  the  direc- 
tion. 


2.2.2  Overall  Program 

The  Overall  Program  Is  documented  with  a Program  Flow  Diagram  containing 
one  block  for  each  major  routine.  One  block  Is  Included  for  each  peripheral 
device  which  provides  an  Input  to,  or  receives  an  output  from,  the  computer 
being  programmed.  Major  routines  within  the  overall  program  have  a single  Input 
but  may  have  one,  or  two,  outputs.  Major  routines  are  subgrouped  to  Identify 
subroutines  within  the  major  routine,  and  to  Illustrate  the  relationship  and 
flow  between  the  subroutines.  A functional  flow  chart  Is  not  normally  prepared 
for  the  Overall  Program. 

2.2.3  Major  Routines 

Major  Routines  are  documented  with  Program  Flow  Diagrams  containing  one 
block  for  each  subroutine  (which  is,  in  turn.  Illustrated  by  a separate  diagram). 
These  diagrams  also  contain  decision  symbols,  where  applicable,  to  Illustrate 
decision  criteria  for  entry  Into  the  subroutine.  Flow  lines  illustrate  flow 
between  the  subroutines.  Functional  Flow  Charts  may  be  provided  at  this  program 
level,  depending  upon  the  complexity  of  the  program. 

2.2.4  Major  Subroutines 

Major  Subroutines  are  documented  with  both  Program  Flow  Diagrams  and 
Functional  Flow  Charts  Illustrating,  by  appropriate  programming  symbols,  the 
individual  decision,  the  Individual  action  to  be  performed  In  the  process  illus- 
trated by  the  diagrams,  and  the  tie-ins  to  the  subfunctional  diagram(s)  that  pro- 
duce the  input,  and  receive  the  output. 

2.2.5  Identification 

Major  routines  are  identified  by  name  only.  However,  each  grouping  block 
at  each  level  has  an  Identifying  number  with  a decimal  Indenture  used  to  indicate 
subordination  of  groupings.  Numbers  between  the  first  and  second  decimal  Indicate 
major  subroutines  within  major  routines.  Numbers  between  the  second  and  third 
decimal  Indicate  subroutines  within  major  subroutines.  Additional  subordinate 
numbering  is  used  as  required  to  identify  the  subordinate  groupings  within  the 
subroutines . 
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TABLE  1 (continued) 


Example 


Notes 


Symbol 


Name 


Processing  Symbols  (continued' 


Informative  data,  such  as  the  data 
unit  on  which  the  decision  Is  made 
or  a sense-switch  setting,  may  be 
Included  in  a subdivision  of  the  symbol 


Decision 


Data  Is  routed  to  each  of  two  output 
paths  by  setting  a switch,  either 
"set"  (S)  or  "normal"  (N). 


Switch  and 
Branch 


Informative  data,  such  as  the  sub- 
routine label,  may  be  Included  In  a 
subdivision  of  the  symbol 


Subroutine 


Space 
tor  note 


Manual 

Operation 


Off-line  operation  performed  on 
equipment  not  under  direct  control  of 
the  central  processing  unit 


Punch 

Data 


Auxiliary- 

Equipment 

Operation 


On-line  operation  performed  on  equip- 
ment under  direct  control  of  the  central 
processing  unit.  Informative  data,  such 
as  names  of  data  being  processed,  may  be 
Included  In  a subdivision  of  the  symbol. 


Computer 
Elevat Ion 


i.onaux  illary 
Equipment 
Operation 


Annotation  Symbols 


Used  for  the  inclusion  of  comments  or 
explanatory  notes.  The  broken  line  Is 
extended,  in  the  most  convenient  direc- 
tion, to  the  appropriate  point  on  the 
flow  line 


Indicates  a special  condition  exists 
at  a certain  point 


Assertion 


For  use  in  updating;  should  not  appear 
on  final  charts 


Insertion 


Communication-Link  Symbols 


Represents  data  transmission  from  one 
location  to  another.  Arrows  Indicate 
direction  of  flow 


7R!> 

to  EC 



j --'f.dr.e  / 

! Tapes  on  / 
Transport  . / 

An  off-line  process  geared  to  tne 

speed  of  a human 

2.2.6  Program  Plow  Diagram  and  Functional  Plow  Chart  Symbols 

Symbols  are  used  on  Program  Flow  Diagrams  and  Functional  Flow  Charts  to 
represent  the  functions  of  a data  processing  program  or  system.  Basic  symbols 
are  established  for  the  functions  that  are  ordinarily  Included  In  high-level  flow 
charts;  i.e.,  Input/output,  processing,  and  annotation.  Specialized  symbols  -- 
within  these  categories  --  are  established  for  the  detailed  functions  that  are 
ordinarily  Included  In  low-level  (subroutine)  flow  charts.  The  symbols,  which 
are  listed  and  explained  In  Table  1,  are  In  accordance  with  MIL-STD-682,  Flow 
Chart  Symbols  for  ADP  Systems. 

2.3  Flow  Lines 

Straight  lines  (vertical  or  horizontal)  are  used  to  show  the  flow  of  control 
or  of  data  between  the  symbols  on  a flow  diagram.  Symbols  requiring  two  output 
lines  normally  have  both  output  lines  perpendicular  to  the  input  line.  None  of 
the  lines  — input  or  output  — are  considered  to  be  an  inherent  part  of  any  symbol. 

2.3.1  Direction  of  Flow 

Horizontal  flow  diagramming  Is  required.  Directional  flow  of  inputs  and 
outputs  is  left  to  right,  unless  otherwise  indicated.  A connection  of  lines  to 
the  grouping  boxes  Indicates  program  sequence.  Lines  passing  left  to  right 
through  a grouping  box  Indicate  that  the  decision  or  action  listed  in  the  box 
must  be  performed  before  the  program  can  proceed.  Lines  entering  a grouping 
box  from  the  top,  or  from  the  left,  with  no  line  leaving  the  right  of  the  box, 
indicate  an  action  that  must  be  performed  at  this  time.  However,  subsequent 
program  operations  within  this  subroutine  are  not  dependent  on  the  results  of 
this  action. 

2.3.2  Fixed  and  Optional  Sequences 

Fixed  sequences  and  optional  sequences  are  Illustrated  on  the  Program  Flow 
Diagram  as  follows: 

(l)  Actions  that  must  be  performed  sequentially: 


(2)  Sequences  of  actions  that  may  be  performed  in  optional  sequence: 


Calculate : 

Calculate : 

Calculate : 

d = X - X , = d 

d = X - X , 

d = Y - Y 

x n n-1  y 

x n n-1 

y n n-1 

“1 

— 

Calculate : 

Calculate : 

Calculate : 

d =X„  - X , 

dv  = X - X , = d 

dv  = Y - Y 

x n n-1 

x n n-1  y 

x in  iri_i 

7 


Optional  sequences  are  prohibited  on  Functional  Flow  Charts  since  they  illustrate 
the  order  in  which  the  options  have  been  exercised. 

(3)  Actions  that  must  be  performed  at  this  time  in  the  program  but  can  be 
performed  in  any  sequence  (the  person  doing  the  coding  may  find  an  opportunity 
to  improve  program  efficiency  by  changing  the  sequence  of  action): 


2.3.3  AND-OR  Decisions 

Flow  lines  illustrate  actions  associated  with  AND  and  OR  decision  as  follows: 
(l)  OR  decision: 


On  Program  Flow  Diagrams,  the  illustration  implies  optional  sequence ; on 
Functional  Flow  Charts,  the  actual  testing  sequence  is  from  left  to  right, 
with  the  first  test  provided  in  the  left  symbol. 


j 


2.3.^  Notations 

Internal  consistency  Is  maintained  In  Program  Plow  Diagrams  and  Functional 
Plow  Charts  by  adherence  to  the  following  rules: 

• All  text  words  have  Initial  capitals,  with  the  remaining  letters  In 
lower  case. 

. References  to  programs  and  data  units,  when  they  are  the  names  used  In 
the  computer  program,  are  all  In  capital  letters. 

• References  to  hardware  labels  appear  as  found  on  the  hardware. 

• No  question  marks  are  placed  at  the  end  of  the  text  In  a decision  box; 
the  symbol  Itself  Indicates  a question. 

• Text  Is  condensed  to  fit  within  the  symbols;  abbreviations  are  avoided 
where  possible. 

• Mathematical  notation  Is  minimized  unless  expressing  complete  equations. 
Where  possible,  text  Is  In  ordinary  English  in  terms  that  can  be  easily 
understood. 

• Questions  are  phrased  (in  decision  boxes)  so  that  they  can  be  answered 
with  a "Yes"  or  "No".  Other  responses  are  permissible;  e.g.,>, <,  = , 
and  combinations  thereof.  If  the  decisions  are  expressed  in  English 
words,  the  first  letter  of  each  word  is  capitalized. 


• Action  illustrated  by  an  action  box  Is  indicated  by  a statement  of  the 
action  in  the  upper  left  comer  of  the  box;  i.e..  Set:,  Subtract:, 
Compute:,  Increment:,  etc.  The  action  to  be  performed  is  indicated  on 


I the  following  lines  within  the  box. 


2.3.5  Annotated  LI a tings 

Annotated  listings  describing  program  implementation  are  also  required  in 
addition  to  Program  Plow  Diagrams  and  Functional  Flow  Charts.  ARINC  Research 
Publication  414-04-4-692  presents  the  requirements  for  preparing  such  listings. 
Examples  from  this  publication  are  given  in  the  following  chapter. 


3.  EXAMPLE  OF  COMPUTER  PROGRAM  DOCUMENTATION 


The  following  documents  are  examples  of  computer  documentation  Introduced 
In  ARINC  Research  Publication  414-04-4-692: 

• Program  Flow  Diagram  (Major  Routine) 

• Major  Subroutine  Program  Flow  Diagram  (with  Functional  Description  of 
Logic  Flow) 

• Major  Subroutine  Functional  Flow  Chart 

They  represent  the  type  of  computer  program  documentation  that  replaces  the 
conventional  flow  chart  shown  In  the  Appendix.  The  three  documents  are  discussed 
In  turn  In  the  following  sections. 

3.1  Program  Flow  Diagram  (Major  Routine) 

The  Program  Flow  Diagram  shown  In  Figure  1 provides  a visibility  of  the 
Major  Routine  (Tracking)  that  is  not  available  from  the  documentation  shown  In 
the  Appendix.  The  Interrelationships  of  the  18  major  subroutines  are  also 
clearly  illustrated;  the  Tracking  Routine  Is  Identified  by  name  only,  whereas 
each  of  the  major  subroutines  is  Identified  by  name  and  number. 

3 . 2 Program  Flow  Diagram  (Major  Subroutine) 

The  Program  Flow  Diagram  shown  in  Figure  2 Is  an  example  of  a Major  Sub- 
routine Flow  Diagram;  a diagram  such  as  this  is  prepared  for  each  major  sub- 
routine. In  this  case,  the  diagram  is  for  subroutine  number  13  (Height  Processing 
Subroutine).  Subroutine  13.1  describes  height  processing  for  surface  targets, 
while  13.2  shows  height  processing  for  air  targets.  Within  subroutine  13.1  are 
sub-subroutines  13.1.1,  Height  Zone;  13.1.2,  Surface  Counter;  and  13.1.3, 

Establish  Surface  Track.  Similar  sub-subroutines  are  shown  for  subroutine  13.2. 

Understanding  of  the  program  is  enhanced  by  providing  brief  functional 
descriptions  of  each  numerically  identified  subroutine.  The  functional 
description  of  logic  flow  for  subroutine  13  (shown  in  Figure  3)  demonstrates 
how  easily  this  understanding  can  be  achieved  by  using  such  documentation. 

3.3  Functional  Flow  Chart  (Major  Subroutine) 

The  Functional  Flow  Chart  shown  in  Figure  4 is  similar  (but  not  identical) 
to  the  Program  Flow  Diagram  of  Figure  2,  which  is  designed  to  illustrate  the 
logical  method  by  which  the  number  13  Height  Processing  Subroutine  was  implemented. 
Subroutines  within  the  number  13  subroutine  are  identified  with  regard  to  their 
logical  implementation.  An  annotated  listing  (not  shown)  is  also  required  to 
further  define  the  manner  of  logic  implementation.  This  documentation  provides 
a method  for  identifying  and  controlling  program  changes  so  that  only  the  specific 
program  steps  requiring  changes  are  affected. 
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EXAMPLE  OF  PROGRAM  FLOW  DIAGRAM; 
MAIOR  SUBROUTINE 


13.  Height-Processing  Subroutine 


The  computer-detector  performs  the  height -finding  process  by  measuring 
the  time-difference  between  the  direct  path  and  the  multi-path  return 
echo.  Results  of  the  CD  test  are  stored  In  the  Height  Accumulator.  In 
addition  to  the  multipath  target  feature,  other  criteria  are  established 
for  Height  Processing.  Conditions  are  provided  In  Figure  2,  13.2. 

Sub-Subroutines 

13.1  Surface  Height  Confirmed  surface  targets  (0  height)  are  processed 

in  this  grouping  (Figure  2,  13.1).  Requirements 
for  confirmed  surface  targets  are  as  follows: 

(a)  Target  not  locked  with  front  tag 

(b)  Target  not  locked  with  rear  tag 

(c)  No  manual  height  entered 

(d)  Valid  one  echo  report 

(e)  Surface  counter  indicates  five  valid  single 
echo  returns 

13.1.1  Height  Zone  In  this  section  the  target  is  tested  for  position 

within  the  height -finding  zone.  The  height -finding 
zone  is  defined  as  further  than  20  miles,  but  closer 
than  200  miles.  When  the  criteria  Is  met,  the  tar- 
get in  Height  Finding  Zone  Bit  Is  set  as  shown  in 
Figure  2,  13.1.1. 

13.1.2  Surface  Counter  Rules  for  counting  valid  echo  for  surface  counter 

are: 

(a)  Ignore  targets  in  obscuration  zone  (front  or 
rear  tag  set) . 

(b)  Increment  valid  echos. 

In  this  grouping  the  front  and  rear  tag  are  tested 
for  target  location  outside  obscuration  zone,  the 
surface  counter  is  tested  to  verify  that  the  surface 
count  is  less  than  5,  and  then  the  surface  counter  i 
incremented  by  one  as  shown  in  Figure  2,  13.1.2. 
Subsequently,  the  surface  counter  is  tested  for 
being  equal  to  five. 

13.1.3  Establish  In  this  section  the  surface  counter  is  tested  for 

Surface  Track  adequate  correlation  of  valid  surface  echos  (sur- 
face counter  equal  to  five)  and,  provided  that 
manual  height  has  not  been  entered,  establishes  the 
target  as  a surface  target  by  setting  present  height 
to  0 and  previous  height  to  maximum.  This  ensures 

a difference  between  present  height  and  previous 
height  greater  than  700  feet,  thus  preventing  false 
returns  from  establishing  this  track  as  an  air  track 
as  shown  in  Figure  2,  13.1.3* 


FIGURE  3 

FUNCTIONAL  DESCRIPTION  OF 
LOGIC  FLOW  FOR  SUBROUTINE  13 
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4.  CONCLUSIONS 


Computer  program  documentation  prepared  In  accordance  with  ARINC  Research 
Publication  414-04-4-692  provides  extensive  Improvements  In: 

• Program  visibility 


• Program  Identification 


• Program  understanding 

• Identification  of  logic  implementation  and  change  control 
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« 5.  RECOMMENDATIONS 

It  Is  recommended  that: 

• Computer  program  documentation  for  new  tactical  data  systems  be  procured 
in  accordance  with  the  requirements  of  ARINC  Research  Publication 
414-04-4-69 

• Computer  program  documentation  for  existing  tactical  data  systems  be 
augmented  with  Program  Flow  Diagrams  and  Functional  Flow  Charts  from  the 
publication  cited  above,  particularly  In  areas  of: 

• Low  reliability 

• High  maintenance  requirements 

• Frequent  occurrence  of  changes 

• Exceptionally  inadequate  existing  documentation 


APPENDIX 


CONVENTIONAL  FLOW  CHARTS 
FOR  A HEIGHT-PROCESS INO  SUBROUTINE 


FIGURE  A-1 

FLOW  CHART  FOR  HEIGHT -PROCESSING  SUBROUTIHE 
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